home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer)…68k, x86, SPARC, PA-RISC] / NeXTSTEP 3.3 Dev Intel.iso / usr / sybase / doc / dbretdata.man < prev    next >
Text File  |  1993-04-22  |  5KB  |  133 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbretdata
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbretdata
  6.  
  7.   FUNCTION:
  8.        Return a pointer to a  return  parameter  value  generated  by  a
  9.        stored procedure.
  10.  
  11.   SYNTAX:
  12.        BYTE *dbretdata(dbproc, retnum)
  13.  
  14.        DBPROCESS *dbproc;
  15.        int       retnum;
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbretdata               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o dbretdata() returns a pointer to a return parameter value  gen-
  30.          erated by a stored procedure.  It is useful in conjunction with
  31.          remote procedure calls and EXECUTE statements  on  stored  pro-
  32.          cedures.
  33.        o Transact-SQL stored procedures can return values for  specified
  34.          "return  parameters."  Changes  made  to  the value of a return
  35.          parameter inside the stored procedure are then available to the
  36.          program  that  called  the procedure.  This is analogous to the
  37.          "pass by reference"  facility  available  in  some  programming
  38.          languages.
  39.  
  40.          For a parameter to function as a return parameter, it  must  be
  41.          declared  as  such  within  the  stored procedure.  The EXECUTE
  42.          statement or remote procedure call that calls the  stored  pro-
  43.          cedure must also indicate that the parameter should function as
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                dbretdata
  47.   ______________________________________________________________________
  48.          a return parameter.  In the case of a remote procedure call, it
  49.          is  the dbrpcparam() routine that specifies whether a parameter
  50.          is a return parameter.
  51.  
  52.        o When executing a  stored  procedure,  the  server  returns  any
  53.          parameter values immediately after returning all other results.
  54.          Therefore, the application can call dbretdata() only after pro-
  55.          cessing  the stored procedure's results by calling dbresults(),
  56.          as well as dbnextrow() if appropriate.   (Note  that  a  stored
  57.          procedure  can  generate  several  sets of results-one for each
  58.          SELECT it contains.  Before the  application  can  call  dbret-
  59.          data() or any other routines that process return parameters, it
  60.          must call dbresults() and dbnextrow() as many times  as  neces-
  61.          sary to process all the results.)
  62.        o If the stored procedure is  invoked  with  a  remote  procedure
  63.          call,  the  return parameter values are automatically available
  64.          to  the  application.   If,  on  the  other  hand,  the  stored
  65.  
  66.  
  67.  
  68.   dbretdata               Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          procedure is invoked with  an  EXECUTE  statement,  the  return
  71.          parameter  values  are available only if the command batch con-
  72.          taining the EXECUTE statement uses local  variables,  not  con-
  73.          stants, for the return parameters.
  74.  
  75.        o Other  routines  return  additional  information  about  return
  76.          parameter values:
  77.           o dbnumrets() returns the total  number  of  return  parameter
  78.             values.
  79.  
  80.           o dbretlen() returns the length of a parameter value.
  81.           o dbretname() returns the name of a parameter value.
  82.  
  83.           o dbrettype() returns the datatype of a parameter value.
  84.        o For an example of this routine, see Example 8 in the DB-Library
  85.          Reference Supplement.
  86.  
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                dbretdata
  91.   ______________________________________________________________________
  92.  
  93.   PARAMETERS:
  94.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  95.            connection for a particular front-end/SQL Server process.  It
  96.            contains all the information that DB-Library uses  to  manage
  97.            communications and data between the front end and SQL Server.
  98.        retnum -  The number of the return parameter value  of  interest.
  99.            The first return value is 1.  Values are returned in the same
  100.            order as the parameters  were  originally  specified  in  the
  101.            stored  procedure's  CREATE  PROCEDURE statement.  (Note that
  102.            this is not necessarily the same order as  specified  in  the
  103.            remote  procedure  call.)  When specifying retnum, non-return
  104.            parameters do not count.  For example, if the second  parame-
  105.            ter  in  a stored procedure is the only return parameter, its
  106.            retnum is 1, not 2.
  107.  
  108.   RETURNS:
  109.  
  110.  
  111.  
  112.   dbretdata               Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.        A pointer to the specified return value.  If  retnum  is  out  of
  115.        range,  dbretdata()  returns NULL.  To determine whether the data
  116.        really has a null value (and retnum is not merely out of  range),
  117.        check for a return of 0 from dbretlen().
  118.  
  119.   SEE ALSO:
  120.        dbnextrow, dbnumrets, dbresults, dbretlen, dbretname,  dbrettype,
  121.        dbrpcinit, dbrpcparam
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.